Hub Python Library documentation
Hub에서 파일 다운로드
Hub에서 파일 다운로드
huggingface_hub 라이브러리는 Hub에 저장된 리포지토리에서 파일을 다운로드하는 함수를 제공합니다. 이러한 함수를 독립적으로 사용하거나 자체 라이브러리에 통합하여 사용자가 Hub와 상호작용하는 것을 더 편리하게 만들 수 있습니다. 이 가이드에서는 다음을 보여줍니다:
- 단일 파일을 다운로드하고 캐시합니다.
- 전체 저장소를 다운로드하고 캐시에 저장합니다.
- 로컬 폴더로 파일을 다운로드합니다.
Download a single file
hf_hub_download() 함수는 Hub에서 파일을 다운로드하는 주요 함수입니다. 이 함수는 원격 파일을 다운로드하고 디스크에 캐시(버전 인식 방식)한 후, 해당 파일의 로컬 경로를 반환합니다.
반환된 파일 경로는 HF 로컬 캐시를 가리키는 포인터입니다. 따라서 캐시가 손상되지 않도록 파일을 수정하지 않는 것이 중요합니다. 파일 캐싱 방식에 대해 더 자세히 알고 싶으시다면 캐싱 가이드를 참고하세요.
최신 버전
repo_id, repo_type, filename 매개변수를 사용하여 다운로드할 파일을 선택합니다. 기본적으로 파일은 model 저장소의 일부로 간주됩니다.
>>> from huggingface_hub import hf_hub_download
>>> hf_hub_download(repo_id="lysandre/arxiv-nlp", filename="config.json")
'/root/.cache/huggingface/hub/models--lysandre--arxiv-nlp/snapshots/894a9adde21d9a3e3843e6d5aeaaf01875c7fade/config.json'
# Download from a dataset
>>> hf_hub_download(repo_id="google/fleurs", filename="fleurs.py", repo_type="dataset")
'/root/.cache/huggingface/hub/datasets--google--fleurs/snapshots/199e4ae37915137c555b1765c01477c216287d34/fleurs.py'특정 버전
기본적으로 main 브랜치의 최신 버전이 다운로드됩니다. 그러나 특정 버전(예: 특정 브랜치, PR, 태그 또는 커밋 해시)의 파일을 다운로드해야 하는 경우가 있습니다.
이 경우 revision 매개변수를 사용하세요:
# Download from the `v1.0` tag
>>> hf_hub_download(repo_id="lysandre/arxiv-nlp", filename="config.json", revision="v1.0")
# Download from the `test-branch` branch
>>> hf_hub_download(repo_id="lysandre/arxiv-nlp", filename="config.json", revision="test-branch")
# Download from Pull Request #3
>>> hf_hub_download(repo_id="lysandre/arxiv-nlp", filename="config.json", revision="refs/pr/3")
# Download from a specific commit hash
>>> hf_hub_download(repo_id="lysandre/arxiv-nlp", filename="config.json", revision="877b84a8f93f2d619faa2a6e514a32beef88ab0a")참고: 커밋 해시를 사용할 경우, 7자 커밋 해시가 아닌 전체 길이의 해시를 사용해야 합니다.
다운로드 URL 구성
리포지토리에서 파일을 다운로드하는 데 사용되는 URL을 직접 구성하려면 URL을 반환하는 hf_hub_url()을 사용할 수 있습니다. 이 함수는 hf_hub_download() 내부에서 사용됩니다.
전체 저장소 다운로드
snapshot_download()은 주어진 리비전의 저장소 전체를 다운로드합니다. 내부적으로 hf_hub_download()을 사용하므로 모든 다운로드된 파일은 로컬 디스크에도 캐시됩니다. 프로세스를 가속하기 위해 다운로드가 병렬로 수행됩니다.
전체 저장소를 다운로드하려면 repo_id와 repo_type만 전달하면 됩니다:
>>> from huggingface_hub import snapshot_download
>>> snapshot_download(repo_id="lysandre/arxiv-nlp")
'/home/lysandre/.cache/huggingface/hub/models--lysandre--arxiv-nlp/snapshots/894a9adde21d9a3e3843e6d5aeaaf01875c7fade'
# Or from a dataset
>>> snapshot_download(repo_id="google/fleurs", repo_type="dataset")
'/home/lysandre/.cache/huggingface/hub/datasets--google--fleurs/snapshots/199e4ae37915137c555b1765c01477c216287d34'snapshot_download()은 기본적으로 최신 리비전을 다운로드합니다. 특정 저장소 리비전을 사용하려면 revision 매개변수를 사용하세요:
>>> from huggingface_hub import snapshot_download
>>> snapshot_download(repo_id="lysandre/arxiv-nlp", revision="refs/pr/1")다운로드할 파일 필터링
snapshot_download()은 저장소를 다운로드하는 간단한 방법을 제공합니다. 하지만 저장소의 전체 내용을 다운로드하고 싶지 않은 경우도 있습니다. 예를 들어, .safetensors 가중치만 사용할 것임을 알고 있다면 모든 .bin 파일의 다운로드를 방지할 수 있습니다. allow_patterns 및 ignore_patterns 매개변수를 사용하면 이를 수행할 수 있습니다.
이 매개변수는 단일 패턴 또는 패턴 목록을 받아들입니다. 패턴은 여기에 문서화된 표준 와일드카드(globbing 패턴)입니다. 패턴 매칭은 fnmatch에 기반합니다.
예를 들어, allow_patterns를 사용하여 JSON 구성 파일만 다운로드할 수 있습니다:
>>> from huggingface_hub import snapshot_download
>>> snapshot_download(repo_id="lysandre/arxiv-nlp", allow_patterns="*.json")반면, ignore_patterns는 다운로드에서 특정 파일을 제외하는 데 사용할 수 있습니다. 다음 예제는 .msgpack 및 .h5 파일 확장자를 무시합니다:
>>> from huggingface_hub import snapshot_download
>>> snapshot_download(repo_id="lysandre/arxiv-nlp", ignore_patterns=["*.msgpack", "*.h5"])마지막으로, 두 가지를 조합하여 다운로드를 정확하게 필터링할 수 있습니다. vocab.json를 제외한 모든 json 및 markdown 파일을 다운로드하는 예시를 보여줍니다.
>>> from huggingface_hub import snapshot_download
>>> snapshot_download(repo_id="gpt2", allow_patterns=["*.md", "*.json"], ignore_patterns="vocab.json")Download file(s) to a local folder
기본적으로 Hub에서 파일을 다운로드할 때 캐시 시스템을 사용하는 것을 권장합니다. hf_hub_download()와 snapshot_download()의 cache_dir 매개변수를 사용하여 사용자 지정 캐시 위치를 지정하거나, HF_HOME 환경 변수를 설정하여 지정할 수 있습니다.
다만, 특정 폴더로 파일을 다운로드해야 하는 경우 다운로드 함수에 local_dir 매개변수를 전달할 수 있습니다. 이는 git 명령이 제공하는 워크플로에 더 가깝게 만드는 데 유용합니다. 다운로드된 파일은 지정된 폴더 내에서 원래의 파일 구조를 유지합니다. 예를 들어, filename="data/train.csv"이고 local_dir="path/to/folder"인 경우, 결과 파일 경로는 "path/to/folder/data/train.csv"가 됩니다.
로컬 디렉터리의 루트에 .cache/huggingface/ 폴더가 생성되며, 다운로드된 파일에 대한 메타데이터를 포함합니다. 이미 최신 상태인 파일은 다시 다운로드하지 않도록 방지합니다. 메타데이터가 변경된 경우, 새로운 파일 버전이 다운로드됩니다. 이를 통해 local_dir은 최신 변경 사항만 가져오도록 최적화됩니다.
다운로드가 완료되면 더 이상 필요하지 않다면 .cache/huggingface/ 폴더를 안전하게 삭제할 수 있습니다. 하지만 이 폴더 없이 스크립트를 다시 실행하면 메타데이터가 손실되어 복구 시간이 더 길어질 수 있습니다. 로컬 데이터는 그대로 유지되며 영향을 받지 않습니다.
Hub에 변경 사항을 커밋할 때
.cache/huggingface/폴더에 대해 걱정하지 마세요. 이 폴더는git와 upload_folder() 양쪽에서 자동으로 무시됩니다.
CLI에서 다운로드
터미널에서 hf download 명령을 사용하여 Hub에서 파일을 직접 다운로드할 수 있습니다.
내부적으로 위와 같이 설명된 동일한 hf_hub_download() 및 snapshot_download() 헬퍼를 사용하며 반환된 경로를 터미널에 출력합니다.
>>> hf download gpt2 config.json
/home/wauplin/.cache/huggingface/hub/models--gpt2/snapshots/11c5a3d5811f50298f278a704980280950aedb10/config.json여러 파일을 한 번에 다운로드할 수 있으며, 진행률 표시줄을 표시하고 파일이 저장된 스냅샷 경로를 반환합니다:
>>> hf download gpt2 config.json model.safetensors
Fetching 2 files: 100%|████████████████████████████████████████████| 2/2 [00:00<00:00, 23831.27it/s]
/home/wauplin/.cache/huggingface/hub/models--gpt2/snapshots/11c5a3d5811f50298f278a704980280950aedb10hf:// URI 하나를 사용하여 리포지토리(선택적으로 리비전 및 파일)를 지정할 수도 있습니다. URI 문법은 hf://[<TYPE>/]<ID>[@<REVISION>][/<PATH>]를 따르며(전체 문법은 HF URIs reference를 참조), --repo-type 및 --revision 옵션을 대체합니다. 이 옵션들은 해당 URI와 함께 설정할 수 없습니다:
# Download a single file from a dataset at a given revision
>>> hf download hf://datasets/google/fleurs@refs/pr/1/fleurs.py
# Download a subfolder (note the trailing slash)
>>> hf download hf://datasets/google/fleurs/data/
# Download an entire repo
>>> hf download hf://datasets/google/fleursCLI 다운로드 명령에 대한 자세한 내용은 CLI 가이드를 참고하세요.
Dry-run 모드
일부 경우, 실제로 파일을 다운로드하기 전에 어떤 파일이 다운로드될지 확인하고 싶을 수 있습니다. --dry-run 매개변수를 사용하여 이를 확인할 수 있습니다. 이 매개변수는 저장소의 모든 다운로드 대상 파일을 나열하고, 해당 파일이 이미 다운로드되었는지 여부를 확인합니다. 이를 통해 다운로드해야 하는 파일의 수와 크기를 파악할 수 있습니다.
단일 파일에 대해 확인하는 예시입니다:
>>> hf download openai-community/gpt2 onnx/decoder_model_merged.onnx --dry-run
[dry-run] Will download 1 files (out of 1) totalling 655.2M
File Bytes to download
------------------------------ -----------------
onnx/decoder_model_merged.onnx 655.2M그리고 파일이 이미 캐시된 경우:
>>> hf download openai-community/gpt2 onnx/decoder_model_merged.onnx --dry-run
[dry-run] Will download 0 files (out of 1) totalling 0.0.
File Bytes to download
------------------------------ -----------------
onnx/decoder_model_merged.onnx -전체 저장소에 대해 dry-run을 실행할 수도 있습니다:
>>> hf download openai-community/gpt2 --dry-run
[dry-run] Fetching 26 files: 100%|█████████████| 26/26 [00:04<00:00, 6.26it/s]
[dry-run] Will download 11 files (out of 26) totalling 5.6G.
File Bytes to download
--------------------------------- -----------------
.gitattributes -
64-8bits.tflite 125.2M
64-fp16.tflite 248.3M
64.tflite 495.8M
README.md -
config.json -
flax_model.msgpack 497.8M
generation_config.json -
merges.txt -
model.safetensors 548.1M
onnx/config.json -
onnx/decoder_model.onnx 653.7M
onnx/decoder_model_merged.onnx 655.2M
onnx/decoder_with_past_model.onnx 653.7M
onnx/generation_config.json -
onnx/merges.txt -
onnx/special_tokens_map.json -
onnx/tokenizer.json -
onnx/tokenizer_config.json -
onnx/vocab.json -
pytorch_model.bin 548.1M
rust_model.ot 702.5M
tf_model.h5 497.9M
tokenizer.json -
tokenizer_config.json -
vocab.json -그리고 파일 필터링을 통해:
>>> hf download openai-community/gpt2 --include "*.json" --dry-run
[dry-run] Fetching 11 files: 100%|█████████████| 11/11 [00:00<00:00, 80518.92it/s]
[dry-run] Will download 0 files (out of 11) totalling 0.0.
File Bytes to download
---------------------------- -----------------
config.json -
generation_config.json -
onnx/config.json -
onnx/generation_config.json -
onnx/special_tokens_map.json -
onnx/tokenizer.json -
onnx/tokenizer_config.json -
onnx/vocab.json -
tokenizer.json -
tokenizer_config.json -
vocab.json -마지막으로, hf_hub_download()과 snapshot_download()에 dry_run=True를 전달하여 프로그래밍 방식으로 dry-run을 수행할 수도 있습니다. 각 파일에 대해 커밋 해시, 파일 이름, 파일 크기, 파일이 캐시되어 있는지 여부, 파일이 다운로드될지 여부를 포함하는 DryRunFileInfo(각각 DryRunFileInfo의 목록)를 반환합니다. 실제로 파일은 캐시되지 않았거나 force_download=True가 전달된 경우 다운로드됩니다.
더 빠른 다운로드
hf_xet를 통해 더 빠른 다운로드를 활용하세요. hf_xet는 xet-core 라이브러리의 Python 바인딩으로, 더 빠른 다운로드와 업로드를 가능하게 하는 청크 기반 중복 제거를 지원합니다. hf_xet는 huggingface_hub와 완벽하게 통합되지만, LFS 대신 Rust xet-core 라이브러리와 Xet 스토리지를 사용합니다.
hf_xet는 파일을 불변(immutable) 청크로 분할하는 Xet 저장 시스템을 사용합니다. 이 시스템은 이러한 청크의 컬렉션(블록 또는 xorb라고 함)을 원격에 저장하고, 요청 시 이를 가져와 파일을 재조립합니다. 다운로드 시, 사용자가 파일에 액세스할 권한이 있는지 확인한 후 hf_xet는 해당 파일의 LFS SHA256 해시로 Xet 콘텐츠 주소 지정 서비스(CAS)에 쿼리를 보내, 이러한 파일을 조립하기 위한 재구성 메타데이터(xorb 내 범위)와 xorb를 직접 다운로드하기 위한 사전 서명된 URL을 수신합니다. 그런 다음 hf_xet는 필요한 xorb 범위를 효율적으로 다운로드하고 디스크에 파일을 기록합니다.
활성화하려면 huggingface_hub의 최신 버전을 설치하면 됩니다:
pip install -U "huggingface_hub"huggingface_hub 0.32.0부터 hf_xet도 함께 설치됩니다.
기타 모든 huggingface_hub API는 수정 없이 계속 작동합니다. Xet 스토리지와 hf_xet의 이점에 대해 자세히 알아보려면 이 섹션을 참조하세요.
참고: hf_transfer는 이전에 LFS 스토리지 백엔드와 함께 사용되었으나 이제 비추천(deprecated)되었습니다. 대신 hf_xet을 사용하세요.